home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / send-pr.info.z / send-pr.info
Encoding:
GNU Info File  |  1998-05-21  |  59.6 KB  |  1,619 lines
  1. This is Info file ../../info/send-pr.info, produced by Makeinfo version
  2. 1.68 from the input file send-pr.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * send-pr: (send-pr).           Reporting problems--using send-pr
  6. END-INFO-DIR-ENTRY
  7.  
  8.    Copyright (C) 1993, 1994, 1995 Free Software Foundation, Inc.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided also
  16. that the entire resulting derived work is distributed under the terms
  17. of a permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions.
  22.  
  23. 
  24. File: send-pr.info,  Node: Top,  Next: send-pr in detail,  Up: (dir)
  25.  
  26. Overview
  27. ********
  28.  
  29.    This manual documents `send-pr', version 3.101, which uses
  30. electronic mail to submit support questions and problem reports to a
  31. central Support Site.  No body of work is perfect, and support
  32. organizations understand this; `send-pr' is designed to allow users who
  33. have problems to submit reports of these problems to sites responsible
  34. for supporting the products in question, in a defined form which can be
  35. read by an electronically managed database.
  36.  
  37.    `send-pr' is part of a suite of programs known collectively as
  38. GNATS, the GNU Problem Report Management System.  GNATS consists of
  39. several programs which, used in concert, formulate and partially
  40. administer a database of "Problem Reports", or "PRs", at a central
  41. Support Site.  A PR goes through several states in its lifetime; GNATS
  42. tracks the PR and all information associated with it through each state
  43. and finally acts as an archive for PRs which have been "closed".
  44.  
  45.    Because `send-pr' exists as a shell (`/bin/sh') script and as an
  46. Elisp file for use with GNU Emacs, it can be used from any machine on
  47. your network which can run a shell script and/or Emacs.
  48.  
  49.    In general, you can use any editor and mailer to submit valid Problem
  50. Reports, as long as the format required by GNATS is preserved.
  51. `send-pr' automates the process, however, and ensures that certain
  52. fields necessary for automatic processing are present.  `send-pr' is
  53. strongly recommended for all initial problem-oriented correspondence
  54. with your Support Site.  The organization you submit Problem Reports to
  55. supplies an address to which further information can be sent; the person
  56. responsible for the category of the problem you report contacts you
  57. directly.
  58.  
  59. * Menu:
  60.  
  61. * send-pr in detail::     Details about send-pr and GNATS
  62. * Invoking send-pr::      Editing and sending PRs
  63. * An Example::            A working example
  64. * Installing send-pr::    Installing send-pr on your system
  65. * Index::
  66.  
  67. 
  68. File: send-pr.info,  Node: send-pr in detail,  Next: Invoking send-pr,  Prev: Top,  Up: Top
  69.  
  70. Details about send-pr and GNATS
  71. *******************************
  72.  
  73.    A "Problem Report" is a message that describes a problem you are
  74. having with a body of work.  `send-pr' organizes this message into a
  75. form which can be understood and automatically processed by GNATS, the
  76. GNU Problem Report Management System.  A Problem Report is organized
  77. into "fields" which contain data describing you, your organization, and
  78. the problem you are announcing (*note Problem Report format: Fields.).
  79. Problem Reports go through several defined states in their lifetimes,
  80. from "open" to "closed" (*note States of Problem Reports: States.).
  81.  
  82. * Menu:
  83.  
  84. * States::                     States of Problem Reports
  85. * Fields::                     Problem Report format
  86.  
  87. 
  88. File: send-pr.info,  Node: States,  Next: Fields,  Up: send-pr in detail
  89.  
  90. States of Problem Reports
  91. =========================
  92.  
  93.    Each PR goes through a defined series of states between origination
  94. and closure.  The originator of a PR receives notification
  95. automatically of any state changes.
  96.  
  97. "open"
  98.      The initial state of a Problem Report.  This means the PR has been
  99.      filed and the responsible person(s) notified.
  100.  
  101. "analyzed"
  102.      The responsible person has analyzed the problem.  The analysis
  103.      should contain a preliminary evaluation of the problem and an
  104.      estimate of the amount of time and resources necessary to solve
  105.      the problem.  It should also suggest possible workarounds.
  106.  
  107. "feedback"
  108.      The problem has been solved, and the originator has been given a
  109.      patch or other fix.  The PR remains in this state until the
  110.      originator acknowledges that the solution works.
  111.  
  112. "closed"
  113.      A Problem Report is closed ("the bug stops here") only when any
  114.      changes have been integrated, documented, and tested, and the
  115.      submitter has confirmed the solution.
  116.  
  117. "suspended"
  118.      Work on the problem has been postponed.  This happens if a timely
  119.      solution is not possible or is not cost-effective at the present
  120.      time.  The PR continues to exist, though a solution is not being
  121.      actively sought.  If the problem cannot be solved at all, it
  122.      should be closed rather than suspended.
  123.  
  124. 
  125. File: send-pr.info,  Node: Fields,  Prev: States,  Up: send-pr in detail
  126.  
  127. Problem Report format
  128. =====================
  129.  
  130.    The format of a PR is designed to reflect the nature of GNATS as a
  131. database.  Information is arranged into "fields", and kept in
  132. individual records (Problem Reports).
  133.  
  134.    Problem Report fields are denoted by a keyword which begins with `>'
  135. and ends with `:', as in `>Confidential:'.  Fields belong to one of
  136. three data types:
  137.  
  138. ENUMERATED
  139.      One of a specific set of values, which vary according to the
  140.      field.  The value for each keyword must be on the same line as the
  141.      keyword.  These values are not configurable (yet).
  142.  
  143.      For each ENUMERATED keyword, the possible choices are listed in the
  144.      `send-pr' template as a comment.  The following fields are
  145.      ENUMERATED format; see the descriptions of fields below for
  146.      explanations of each field in detail:
  147.  
  148.           >Confidential:   >Severity:       >Priority:
  149.           >Class:          >State:          >Number:
  150.  
  151. TEXT
  152.      One single line of text which must begin and end on the same line
  153.      (i.e., before a newline) as the keyword.  See the descriptions of
  154.      fields below for explanations of each field in detail.  The
  155.      following fields are TEXT format:
  156.  
  157.           >Submitter-Id:   >Originator:     >Synopsis:
  158.           >Category:       >Release:        >Responsible:
  159.           >Arrival-Date:
  160.  
  161. MULTITEXT
  162.      Text of any length may occur in this field.  MULTITEXT may span
  163.      multiple lines and may also include blank lines.  A MULTITEXT field
  164.      ends only when another keyword appears.  See the descriptions of
  165.      fields below for explanations of each field in detail.
  166.  
  167.      The following fields are MULTITEXT format:
  168.  
  169.           >Organization:   >Environment:    >Description:
  170.           >How-To-Repeat:  >Fix:            >Audit-Trail:
  171.           >Unformatted:
  172.  
  173.    A Problem Report contains two different types of fields: "Mail
  174. Header" fields, which are used by the mail handler for delivery, and
  175. "Problem Report" fields, which contain information relevant to the
  176. Problem Report and its submitter.  A Problem Report is essentially a
  177. specially formatted electronic mail message.
  178.  
  179.    The following is an example Problem Report.  Mail headers are at the
  180. top, followed by GNATS fields, which begin with `>' and end with `:'.
  181. The `Subject:' line in the mail header and the `>Synopsis:' field are
  182. usually duplicates of each other.
  183.  
  184.      Message-Id:  MESSAGE-ID
  185.      Date:        DATE
  186.      From:        ADDRESS
  187.      Reply-To:    ADDRESS
  188.      To:          BUG-ADDRESS
  189.      Subject:     SUBJECT
  190.      
  191.      >Number:       GNATS-ID
  192.      >Category:     CATEGORY
  193.      >Synopsis:     SYNOPSIS
  194.      >Confidential: yes *or* no
  195.      >Severity:     critical, serious, *or* non-critical
  196.      >Priority:     high, medium *or* low
  197.      >Responsible:  RESPONSIBLE
  198.      >State:        open, analyzed, suspended, feedback, *or* closed
  199.      >Class:        sw-bug, doc-bug, change-request, support,
  200.      *or* duplicate
  201.      >Submitter-Id: SUBMITTER-ID
  202.      >Arrival-Date: DATE
  203.      >Originator:   NAME
  204.      >Organization: ORGANIZATION
  205.      >Release:      RELEASE
  206.      >Environment:
  207.         ENVIRONMENT
  208.      >Description:
  209.         DESCRIPTION
  210.      >How-To-Repeat:
  211.         HOW-TO-REPEAT
  212.      >Fix:
  213.         FIX
  214.      >Audit-Trail:
  215.      APPENDED-MESSAGES...
  216.      State-Changed-From-To: FROM-TO
  217.      State-Changed-When: DATE
  218.      State-Changed-Why:
  219.         REASON
  220.      Responsible-Changed-From-To: FROM-TO
  221.      Responsible-Changed-When: DATE
  222.      Responsible-Changed-Why:
  223.         REASON
  224.      >Unformatted:
  225.         MISCELLANEOUS
  226.  
  227. * Menu:
  228.  
  229. * Mail header fields::
  230. * Problem Report fields::
  231.  
  232. 
  233. File: send-pr.info,  Node: Mail header fields,  Next: Problem Report fields,  Up: Fields
  234.  
  235. Mail header fields
  236. ------------------
  237.  
  238.    A Problem Report may contain any mail header field described in the
  239. Internet standard RFC-822.  However, only the fields which identify the
  240. sender and the subject are required by `send-pr':
  241.  
  242. `To:'
  243.      The preconfigured mail address for the Support Site where the PR
  244.      is to be sent, automatically supplied by `send-pr'.
  245.  
  246. `Subject:'
  247.      A terse description of the problem.  This field normally contains
  248.      the same information as the `>Synopsis:' field.
  249.  
  250. `From:'
  251.      Usually supplied automatically by the originator's mailer; should
  252.      contain the originator's electronic mail address.
  253.  
  254. `Reply-To:'
  255.      A return address to which electronic replies can be sent; in most
  256.      cases, the same address as the `From:' field.
  257.  
  258. 
  259. File: send-pr.info,  Node: Problem Report fields,  Prev: Mail header fields,  Up: Fields
  260.  
  261. Problem Report fields
  262. ---------------------
  263.  
  264. Field descriptions
  265. ------------------
  266.  
  267.    The following fields are present whenever a PR is submitted via the
  268. program `send-pr'.  GNATS adds additional fields when the PR arrives at
  269. the Support Site; explanations of these follow this list.
  270.  
  271. `>Submitter-Id:'
  272.      (TEXT) A unique identification code assigned by the Support Site.
  273.      It is used to identify all Problem Reports coming from a particular
  274.      site.  (Submitters without a value for this field can invoke
  275.      `send-pr' with the `--request-id' option to apply for one from the
  276.      support organization.  Problem Reports from those not affiliated
  277.      with the support organization should use the default value of `net'
  278.      for this field.)
  279.  
  280. `>Originator:'
  281.      (TEXT) Originator's real name.  The default is the value of the
  282.      originator's environment variable `NAME'.
  283.  
  284. `>Organization:'
  285.      (MULTITEXT) The originator's organization.  The default value is
  286.      set with the variable `DEFAULT_ORGANIZATION' in the `send-pr'
  287.      shell script.
  288.  
  289. `>Confidential:'
  290.      (ENUMERATED) Use of this field depends on the originator's
  291.      relationship with the support organization; contractual agreements
  292.      often have provisions for preserving confidentiality.  Conversely,
  293.      a lack of a contract often means that any data provided will not
  294.      be considered confidential.  Submitters should be advised to
  295.      contact the support organization directly if this is an issue.
  296.  
  297.      If the originator's relationship to the support organization
  298.      provides for confidentiality, then if the value of this field is
  299.      `yes' the support organization treats the PR as confidential; any
  300.      code samples provided are not made publicly available (e.g., in
  301.      regression test suites).  The default value is `yes'.
  302.  
  303. `>Synopsis:'
  304.      (TEXT) One-line summary of the problem.  `send-pr' copies this
  305.      information to the `Subject:' line when you submit a Problem
  306.      Report.
  307.  
  308. `>Severity:'
  309.      (ENUMERATED) The severity of the problem.  Accepted values include:
  310.  
  311.     `critical'
  312.           The product, component or concept is completely
  313.           non-operational or some essential functionality is missing.
  314.           No workaround is known.
  315.  
  316.     `serious'
  317.           The product, component or concept is not working properly or
  318.           significant functionality is missing.  Problems that would
  319.           otherwise be considered `critical' are rated `serious' when a
  320.           workaround is known.
  321.  
  322.     `non-critical'
  323.           The product, component or concept is working in general, but
  324.           lacks features, has irritating behavior, does something
  325.           wrong, or doesn't match its documentation.
  326.  
  327.      The default value is `serious'.
  328.  
  329. `>Priority:'
  330.      (ENUMERATED) How soon the originator requires a solution.  Accepted
  331.      values include:
  332.  
  333.     `high'
  334.           A solution is needed as soon as possible.
  335.  
  336.     `medium'
  337.           The problem should be solved in the next release.
  338.  
  339.     `low'
  340.           The problem should be solved in a future release.
  341.  
  342.      The default value is `medium'.
  343.  
  344. `>Category:'
  345.      (TEXT) The name of the product, component or concept where the
  346.      problem lies.  The values for this field are defined by the Support
  347.      Site.
  348.  
  349. `>Class:'
  350.      (ENUMERATED) The class of a problem can be one of the following:
  351.  
  352.     `sw-bug'
  353.           A general product problem.  (`sw' stands for "software".)
  354.  
  355.     `doc-bug'
  356.           A problem with the documentation.
  357.  
  358.     `change-request'
  359.           A request for a change in behavior, etc.
  360.  
  361.     `support'
  362.           A support problem or question.
  363.  
  364.     `duplicate (PR-NUMBER)'
  365.           Duplicate PR.  PR-NUMBER should be the number of the original
  366.           PR.
  367.  
  368.      The default is `sw-bug'.
  369.  
  370. `>Release:'
  371.      (TEXT) Release or version number of the product, component or
  372.      concept.
  373.  
  374. `>Environment:'
  375.      (MULTITEXT) Description of the environment where the problem
  376.      occured: machine architecture, operating system, host and target
  377.      types, libraries, pathnames, etc.
  378.  
  379. `>Description:'
  380.      (MULTITEXT) Precise description of the problem.
  381.  
  382. `>How-To-Repeat:'
  383.      (MULTITEXT) Example code, input, or activities to reproduce the
  384.      problem.  The support organization uses example code both to
  385.      reproduce the problem and to test whether the problem is fixed.
  386.      Include all preconditions, inputs, outputs, conditions after the
  387.      problem, and symptoms.  Any additional important information
  388.      should be included.  Include all the details that would be
  389.      necessary for someone else to recreate the problem reported,
  390.      however obvious.  Sometimes seemingly arbitrary or obvious
  391.      information can point the way toward a solution.  See also *Note
  392.      Helpful hints: Helpful hints.
  393.  
  394. `>Fix:'
  395.      (MULTITEXT) A description of a solution to the problem, or a patch
  396.      which solves the problem.  (This field is most often filled in at
  397.      the Support Site; we provide it to the submitter in case she has
  398.      solved the problem.)
  399.  
  400. GNATS adds the following fields when the PR arrives at the Support Site:
  401.  
  402. `>Number:'
  403.      (ENUMERATED) The incremental identification number for this PR.
  404.  
  405.      The `>Number:' field is often paired with the `>Category:' field as
  406.  
  407.           CATEGORY/NUMBER
  408.  
  409.      in subsequent email messages.  This is for historical reasons, as
  410.      well as because Problem Reports are stored in subdirectories which
  411.      are named by category.
  412.  
  413. `>State:'
  414.      (ENUMERATED) The current state of the PR.  Accepted values are:
  415.  
  416.     `open'
  417.           The PR has been filed and the responsible person notified.
  418.  
  419.     `analyzed'
  420.           The responsible person has analyzed the problem.
  421.  
  422.     `feedback'
  423.           The problem has been solved, and the originator has been
  424.           given a patch or other fix.
  425.  
  426.     `closed'
  427.           The changes have been integrated, documented, and tested, and
  428.           the originator has confirmed that the solution works.
  429.  
  430.     `suspended'
  431.           Work on the problem has been postponed.
  432.  
  433.      The initial state of a PR is `open'.  *Note States of Problem
  434.      Reports: States.
  435.  
  436. `>Responsible:'
  437.      (TEXT) The person responsible for this category.
  438.  
  439. `>Arrival-Date:'
  440.      (TEXT) The time that this PR was received by GNATS.  The date is
  441.      provided automatically by GNATS.
  442.  
  443. `>Audit-Trail:'
  444.      (MULTITEXT) Tracks related electronic mail as well as changes in
  445.      the `>State:' and `>Responsible:' fields with the sub-fields:
  446.  
  447.     `State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE'
  448.           The old and new `>State:' field values.
  449.  
  450.     `Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP'
  451.           The old and new `>Responsible:' field values.
  452.  
  453.     `State-Changed-By: NAME'
  454.     `Responsible-Changed-By: NAME'
  455.           The name of the maintainer who effected the change.
  456.  
  457.     `State-Changed-When: TIMESTAMP'
  458.     `Responsible-Changed-When: TIMESTAMP'
  459.           The time the change was made.
  460.  
  461.     `State-Changed-Why: REASON...'
  462.     `Responsible-Changed-Why: REASON...'
  463.           The reason for the change.
  464.  
  465.      The `>Audit-Trail:' field also contains any mail messages received
  466.      by GNATS related to this PR, in the order received.
  467.  
  468. `'
  469.      >Unformatted: (MULTITEXT) Any random text found outside the fields
  470.      in the original Problem Report.
  471.  
  472. 
  473. File: send-pr.info,  Node: Invoking send-pr,  Next: An Example,  Prev: send-pr in detail,  Up: Top
  474.  
  475. Editing and sending PRs
  476. ***********************
  477.  
  478.    You can invoke `send-pr' from a shell prompt or from within GNU
  479. Emacs using `M-x send-pr'.
  480.  
  481. * Menu:
  482.  
  483. * using send-pr::             Creating new Problem Reports
  484. * send-pr in Emacs::          Using send-pr from within Emacs
  485. * send-pr from the shell::    Invoking send-pr from the shell
  486. * Helpful hints::
  487.  
  488. 
  489. File: send-pr.info,  Node: using send-pr,  Next: send-pr in Emacs,  Up: Invoking send-pr
  490.  
  491. Creating new Problem Reports
  492. ============================
  493.  
  494.    Invoking `send-pr' presents a PR "template" with a number of fields
  495. already filled in.  Complete the template as thoroughly as possible to
  496. make a useful bug report.  Submit only one bug with each PR.
  497.  
  498.    A template consists of three sections:
  499.  
  500. "Comments"
  501.      The top several lines of a blank template consist of a series of
  502.      comments that provide some basic instructions for completing the
  503.      Problem Report, as well as a list of valid entries for the
  504.      `>Category:' field.  These comments are all preceded by the string
  505.      `SEND-PR:' and are erased automatically when the PR is submitted.
  506.      The instructional comments within `<' and `>' are also removed.
  507.      (Only these comments are removed; lines you provide that happen to
  508.      have those characters in them, such as examples of shell-level
  509.      redirection, are not affected.)
  510.  
  511. "Mail Header"
  512.      `send-pr' creates a standard mail header.  `send-pr' completes all
  513.      fields except the `Subject:' line with default values.  (*Note
  514.      Problem Report format: Fields.)
  515.  
  516. "GNATS fields"
  517.      These are the informational fields that GNATS uses to route your
  518.      Problem Report to the responsible party for further action.  They
  519.      should be filled out as completely as possible.  (*Note Problem
  520.      Report format: Fields.  Also see *Note Helpful hints: Helpful
  521.      hints.)
  522.  
  523. For examples of a Problem Report template and complete Problem Report,
  524. see *Note An Example::.
  525.  
  526.    The default template contains your preconfigured `>Submitter-Id:'.
  527. `send-pr' attempts to determine values for the `>Originator:' and
  528. `>Organization:' fields (*note Problem Report format: Fields.).
  529. `send-pr' will set the `>Originator:' field to the value of the `NAME'
  530. environment variable if it has been set; similarly, `>Organization:'
  531. will be set to the value of `ORGANIZATION'.  `send-pr' also attempts to
  532. find out some information about your system and architecture, and
  533. places this information in the `>Environment:' field if it finds any.
  534.  
  535.    You may submit problem reports to different Support Sites from the
  536. default site by specifying the alternate site when you invoke
  537. `send-pr'.  Each `site' has its own list of categories for which it
  538. accepts Problem Reports.  (*Note Setting a default SITE: default site.)
  539.  
  540.    `send-pr' also provides the mail header section of the template with
  541. default values in the `To:', `From:', and `Reply-To:' fields.  The
  542. `Subject:' field is empty.
  543.  
  544.    The template begins with a comment section:
  545.  
  546.      SEND-PR: -*- send-pr  -*-
  547.      SEND-PR: Lines starting with `SEND-PR' will be removed
  548.      SEND-PR: automatically as well as all comments (the text
  549.      SEND-PR: below enclosed in `<' and `>').
  550.      SEND-PR:
  551.      SEND-PR: Please consult the document `Reporting Problems
  552.      SEND-PR: Using send-pr' if you are not sure how to fill out
  553.      SEND-PR: a problem report.
  554.      SEND-PR:
  555.      SEND-PR: Choose from the following categories:
  556.  
  557. and also contains a list of valid `>Category:' values for the Support
  558. Site to whom you are submitting this Problem Report.  One (and only
  559. one) of these values should be placed in the `>Category:' field.  A
  560. complete sample bug report, from template to completed PR, is shown in
  561. *Note An Example::.  For a complete list of valid categories, type
  562. `send-pr -L' at your prompt.  *Note Valid Categories: Valid Categories,
  563. for a sample list of categories, .
  564.  
  565.    The mail header is just below the comment section.  Fill out the
  566. `Subject:' field, if it is not already completed using the value of
  567. `>Synopsis:'.  The other mail header fields contain default values.
  568.  
  569.      To: SUPPORT-SITE
  570.      Subject: *complete this field*
  571.      From: YOUR-LOGIN@YOUR-SITE
  572.      Reply-To: YOUR-LOGIN@YOUR-SITE
  573.      X-send-pr-version: send-pr 3.101
  574.  
  575. where SUPPORT-SITE is an alias for the Support Site you wish to submit
  576. this PR to.
  577.  
  578.    The rest of the template contains GNATS fields.  Each field is
  579. either automatically completed with valid information (such as your
  580. `>Submitter-Id:') or contains a one-line instruction specifying the
  581. information that field requires in order to be correct.  For example,
  582. the `>Confidential:' field expects a value of `yes' or `no', and the
  583. answer must fit on one line; similarly, the `>Synopsis:' field expects
  584. a short synopsis of the problem, which must also fit on one line.  Fill
  585. out the fields as completely as possible.  *Note Helpful hints: Helpful
  586. hints, for suggestions as to what kinds of information to include.
  587.  
  588.    In this example, words in *italics* are filled in with
  589. pre-configured information:
  590.  
  591.      >Submitter-Id: *your submitter-id*
  592.      >Originator:   *your name here*
  593.      >Organization:
  594.          *your organization*
  595.      >Confidential:<[ yes | no ] (one line)>
  596.      >Synopsis:    <synopsis of the problem (one line)>
  597.      >Severity:    <[non-critical | serious | critical](one line)>
  598.      >Priority:    <[ low | medium | high ] (one line)>
  599.      >Category:    <name of the product (one line)>
  600.      >Class:       <[sw-bug | doc-bug | change-request | support]>
  601.      >Release:     <release number (one line)>
  602.      >Environment:
  603.               <machine, os, target, libraries (multiple lines)>
  604.      
  605.      >Description:
  606.             <precise description of the problem (multiple lines)>
  607.      >How-To-Repeat:
  608.             <code/input/activities to reproduce (multiple lines)>
  609.      >Fix:
  610.             <how to correct or work around the problem, if known
  611.              (multiple lines)>
  612.  
  613.    When you finish editing the Problem Report, `send-pr' mails it to
  614. the address named in the `To:' field in the mail header.  `send-pr'
  615. checks that the complete form contains a valid `>Category:'.
  616.  
  617.    Your copy of `send-pr' should have already been customized on
  618. installation to reflect your `>Submitter-Id:'.  (*Note Installing
  619. `send-pr' on your system: Installing send-pr.)  If you don't know your
  620. `>Submitter-Id:', you can request it using `send-pr --request-id'.  If
  621. your organization is not affiliated with the site you send Problem
  622. Reports to, a good generic `>Submitter-Id:' to use is `net'.
  623.  
  624.    If your PR has an invalid value in one of the ENUMERATED fields
  625. (*note Problem Report format: Fields.), `send-pr' places the PR in a
  626. temporary file named `/tmp/pbadNNNN' on your machine.  NNNN is the
  627. process identification number given to your current `send-pr' session.
  628. If you are running `send-pr' from the shell, you are prompted as to
  629. whether or not you wish to try editing the same Problem Report again.
  630. If you are running `send-pr' from Emacs, the Problem Report is placed
  631. in the buffer `*send-pr-error*'; you can edit this file and then submit
  632. it with
  633.  
  634.      M-x gnats-submit-pr
  635.  
  636.    Any further mail concerning this Problem Report should be
  637. carbon-copied to the GNATS mailing address as well, with the category
  638. and identification number in the `Subject:' line of the message.
  639.  
  640.      Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT
  641.  
  642. Messages which arrive with `Subject:' lines of this form are
  643. automatically appended to the Problem Report in the `>Audit-Trail:'
  644. field in the order received.
  645.  
  646. 
  647. File: send-pr.info,  Node: send-pr in Emacs,  Next: send-pr from the shell,  Prev: using send-pr,  Up: Invoking send-pr
  648.  
  649. Using `send-pr' from within Emacs
  650. =================================
  651.  
  652.    You can use an interactive `send-pr' interface from within GNU Emacs
  653. to fill out your Problem Report.  We recommend that you familiarize
  654. yourself with Emacs before using this feature (*note Introduction:
  655. (emacs)Introduction.).
  656.  
  657.    Call `send-pr' with `M-x send-pr'.(1)  `send-pr' responds with a
  658. Problem Report template preconfigured for the Support Site from which
  659. you received `send-pr'.  (If you use `send-pr' locally, the default
  660. Support Site is probably your local site.)
  661.  
  662.    You may also submit problem reports to different Support Sites from
  663. the default site.  To use this feature, invoke `send-pr' with
  664.  
  665.      C-u M-x send-pr
  666.  
  667.    `send-pr' prompts you for the name of a SITE.  SITE is an alias on
  668. your local machine which points to an alternate Support Site.
  669.  
  670.    `send-pr' displays the template and prompts you in the minibuffer
  671. with the line:
  672.      >Category: other
  673.  
  674. Delete the default value `other' *in the minibuffer* and replace it
  675. with the keyword corresponding to your problem (the list of valid
  676. categories is in the topmost section of the PR template).  For example,
  677. if the problem you wish to report has to do with the GNU C compiler,
  678. and your support organization accepts bugs submitted for this program
  679. under the category `gcc', delete `other' and then type `gcc[<RET>]'.
  680. `send-pr' replaces the line
  681.  
  682.      >Category:       <name of the product (one line)>
  683.  
  684. in the template with
  685.  
  686.      >Category:       gcc
  687.  
  688. and moves on to another field.
  689.  
  690.    `send-pr' provides name completion in the minibuffer.  For instance,
  691. you can also type `gc[<TAB>]', and `send-pr' attempts to complete the
  692. entry for you.  Typing `g[<TAB>]' may not have the same effect if
  693. several possible entries begin with `g'.  In that case `send-pr' cannot
  694. complete the entry because it cannot determine whether you mean `gcc'
  695. or, for example, `gdb', if both of those are possible categories.
  696. `send-pr' continues to prompt you for a valid entry until you enter one.
  697.  
  698.    `send-pr' prompts you interactively to enter each field for which
  699. there is a range of specific choices.  If you attempt to enter a value
  700. which is not in the range of acceptable entries, `send-pr' responds
  701. with `[No match]' and allows you to change the entry until it contains
  702. an acceptable value.  This avoids unusable information (at least in
  703. these fields) and also avoids typographical errors which could cause
  704. problems later.
  705.  
  706.    `send-pr' prompts you for the following fields:
  707.  
  708.      >Category:
  709.      >Confidential: (*default*:  no)
  710.      >Severity:     (*default*:  serious)
  711.      >Priority:     (*default*:  medium)
  712.      >Class:        (*default*:  sw-bug)
  713.      >Release:
  714.      >Synopsis:     (*this value is copied to `Subject:'*)
  715.  
  716. After you complete these fields, `send-pr' places the cursor in the
  717. `>Description:' field and displays the message
  718.  
  719.      To send the problem report use: C-c C-c
  720.  
  721. in the minibuffer.  At this point, edit the file in the main buffer to
  722. reflect your specific problem, putting relevant information in the
  723. proper fields.  *Note An Example::, for a sample Problem Report.
  724.  
  725.    `send-pr' provides a few key bindings to make moving around in a
  726. template buffer more simple:
  727.  
  728. `C-c C-f'
  729. `M-x change-field'
  730.      Changes the field under the cursor.  `edit-pr' prompts you for a
  731.      new value.
  732.  
  733. `M-C-b'
  734. `M-x gnats-backward-field'
  735.      Moves the cursor to the beginning of the value of the current
  736.      field.
  737.  
  738. `M-C-f'
  739. `M-x gnats-forward-field'
  740.      Moves the cursor to the end of the value of the current field.
  741.  
  742. `M-p'
  743. `M-x gnats-previous-field'
  744.      Moves the cursor back one field to the beginning of the value of
  745.      the previous field.
  746.  
  747. `M-n'
  748. `M-x gnats-next-field'
  749.      Moves the cursor forward one field to the beginning of the value
  750.      of the next field.
  751.  
  752.    `send-pr' takes over again when you type `C-c C-c' to send the
  753. message.  `send-pr' reports any errors in a separate buffer, which
  754. remains in existence until you send the PR properly (or, of course,
  755. until you explicitly kill the buffer).
  756.  
  757.    For detailed instructions on using Emacs, see *Note Introduction:
  758. (emacs)Introduction.
  759.  
  760.    ---------- Footnotes ----------
  761.  
  762.    (1) If typing `M-x send-pr' doesn't work, see your system
  763. administrator for help loading `send-pr' into Emacs.
  764.  
  765. 
  766. File: send-pr.info,  Node: send-pr from the shell,  Next: Helpful hints,  Prev: send-pr in Emacs,  Up: Invoking send-pr
  767.  
  768. Invoking `send-pr' from the shell
  769. =================================
  770.  
  771.      send-pr [ SITE ]
  772.              [ -f PROBLEM-REPORT | --file PROBLEM-REPORT ]
  773.              [ -t MAIL-ADDRESS | --to MAIL-ADDRESS ]
  774.              [ --request-id ]
  775.              [ -L | --list ] [ -P | --print ]
  776.              [ -V | --version] [ -h | --help ]
  777.  
  778.    SITE is an alias on your local machine which points to an address
  779. used by a Support Site.  If this argument is not present, the default
  780. SITE is usually the site which you received `send-pr' from, or your
  781. local site if you use GNATS locally.  (*Note Setting a default SITE:
  782. default site.)
  783.  
  784.    Invoking `send-pr' with no options calls the editor named in your
  785. environment variable `EDITOR' on a default PR template.  If the
  786. environment variable `PR_FORM' is set, its value is used as a file name
  787. which contains a valid template.  If `PR_FORM' points to a missing or
  788. unreadable file, or if the file is empty, `send-pr' generates an error
  789. message and opens the editor on a default template.
  790.  
  791. `-f PROBLEM-REPORT'
  792. `--file PROBLEM-REPORT'
  793.      Specifies a file, PROBLEM-REPORT, where a completed Problem Report
  794.      already exists.  `send-pr' sends the contents of the file without
  795.      invoking an editor.  If PROBLEM-REPORT is `-', `send-pr' reads
  796.      from standard input.
  797.  
  798. `-t MAIL-ADDRESS'
  799. `--to MAIL-ADDRESS'
  800.      Sends the PR to MAIL-ADDRESS. The default is preset when `send-pr'
  801.      is configured.  *This option is not recommended*; instead, use the
  802.      argument SITE on the command line.
  803.  
  804. `-c MAIL-ADDRESS'
  805. `--cc MAIL-ADDRESS'
  806.      Places MAIL-ADDRESS in the `Cc:' header field of the message to be
  807.      sent.
  808.  
  809. `--request-id'
  810.      Sends a request for a `>Submitter-Id:' to the Support Site.
  811.  
  812. `-L'
  813. `--list'
  814.      Prints the list of valid `>Category:' values on standard output.
  815.      No mail is sent.
  816.  
  817. `-s SEVERITY'
  818. `--severity SEVERITY'
  819.      Sets the initial value of the `>Severity:' field to SEVERITY.
  820.  
  821. `-P'
  822. `--print'
  823.      Displays the PR template.  If the variable `PR_FORM' is set in your
  824.      environment, the file it specifies is printed.  If `PR_FORM' is not
  825.      set, `send-pr' prints the standard blank form.  If the file
  826.      specified by `PR_FORM' doesn't exist, `send-pr' displays an error
  827.      message.  No mail is sent.
  828.  
  829. `-V'
  830. `--version'
  831.      Displays the `send-pr' version number and a usage summary.  No mail
  832.      is sent.
  833.  
  834. `-h'
  835. `--help'
  836.      Displays a usage summary for `send-pr'.  No mail is sent.
  837.  
  838. 
  839. File: send-pr.info,  Node: Helpful hints,  Prev: send-pr from the shell,  Up: Invoking send-pr
  840.  
  841. Helpful hints
  842. =============
  843.  
  844.    There is no orthodox standard for submitting effective bug reports,
  845. though you might do well to consult the section on submitting bugs for
  846.  
  847.    GNU `gcc' in *Note Reporting Bugs: (gcc)Bugs, by Richard Stallman.
  848. This section contains instructions on what kinds of information to
  849. include and what kinds of mistakes to avoid.
  850.  
  851.    In general, common sense (assuming such an animal exists) dictates
  852. the kind of information that would be most helpful in tracking down and
  853. resolving problems in software.
  854.    * Include anything *you* would want to know if you were looking at
  855.      the report from the other end.  There's no need to include every
  856.      minute detail about your environment, although anything that might
  857.      be different from someone else's environment should be included
  858.      (your path, for instance).
  859.  
  860.    * Narratives are often useful, given a certain degree of restraint.
  861.      If a person responsible for a bug can see that A was executed, and
  862.      then B and then C, knowing that sequence of events might trigger
  863.      the realization of an intermediate step that was missing, or an
  864.      extra step that might have changed the environment enough to cause
  865.      a visible problem.  Again, restraint is always in order ("I set
  866.      the build running, went to get a cup of coffee (Columbian, cream
  867.      but no sugar), talked to Sheila on the phone, and then THIS
  868.      happened...") but be sure to include anything relevant.
  869.  
  870.    * Richard Stallman writes, "The fundamental principle of reporting
  871.      bugs usefully is this: *report all the facts*.  If you are not sure
  872.      whether to state a fact or leave it out, state it!"  This holds
  873.      true across all problem reporting systems, for computer software
  874.      or social injustice or motorcycle maintenance.  It is especially
  875.      important in the software field due to the major differences
  876.      seemingly insignificant changes can make (a changed variable, a
  877.      missing semicolon, etc.).
  878.  
  879.    * Submit only *one* problem with each Problem Report.  If you have
  880.      multiple problems, use multiple PRs.  This aids in tracking each
  881.      problem and also in analyzing the problems associated with a given
  882.      program.
  883.  
  884.    * It never hurts to do a little research to find out if the bug
  885.      you've found has already been reported.  Most software releases
  886.      contain lists of known bugs in the Release Notes which come with
  887.      the software; see your system administrator if you don't have a
  888.      copy of these.
  889.  
  890.    * The more closely a PR adheres to the standard format, the less
  891.      interaction is required by a database administrator to route the
  892.      information to the proper place.  Keep in mind that anything that
  893.      requires human interaction also requires time that might be better
  894.      spent in actually fixing the problem.  It is therefore in
  895.      everyone's best interest that the information contained in a PR be
  896.      as correct as possible (in both format and content) at the time of
  897.      submission.
  898.  
  899. 
  900. File: send-pr.info,  Node: An Example,  Next: Installing send-pr,  Prev: Invoking send-pr,  Up: Top
  901.  
  902. An Example
  903. **********
  904.  
  905.    Cygnus Support in Mountain View, CA, uses GNATS and `send-pr'
  906. extensively for their support activities.  As a support company, Cygnus
  907. finds problem tracking to be a crucial part of everyday business.
  908. Cygnus supports the GNU compiling tools (including GNATS and `send-pr')
  909. over several many platforms
  910.  
  911.    With each shipment of the Cygnus Support Developer's Kit, customers
  912. receive the latest version of `send-pr', which contains an up-to-date
  913. listing of valid categories (values for the `>Category:' field).  Using
  914. these tools, Cygnus' customers can communicate their problems to Cygnus
  915. effectively and receive automatic confirmation of receipt as well as
  916. notification of changes in the status of their reported problems.  Much
  917. of Cygnus' support mechanism relies on electronic mail.
  918.  
  919.    As an example, let's pretend we're a customer of Cygnus Support, and
  920. that we're having a problem compiling some of our software using the
  921. GNU C compiler, which Cygnus supports.
  922.  
  923.    Assume that we're getting an error in our `bifrabulator' program
  924. wherein the `prestidigitation' routines don't match with the
  925. `whatsitsname'.  We've made sure we're following the rules of the
  926. program and checked the Release Notes from Cygnus and found that the bug
  927. isn't already known.  In other words, we're pretty sure we've found a
  928. bug.
  929.  
  930.    Our first step is to call `send-pr'.  It really doesn't matter
  931. whether we use `send-pr' from the shell or from within Emacs.  Indeed,
  932. if we use Emacs as a primary editor, calling `send-pr' from the shell
  933. is likely to start `send-pr' in an Emacs buffer anyway.  So, since our
  934. company, *Imaginary Software, Ltd.*, uses GNU software extensively,
  935. we're pretty familiar with Emacs, so from within Emacs we type
  936.      M-x send-pr
  937.  
  938. and we're greeted with the following screen:
  939.  
  940.      SEND-PR: -*- text  -*-
  941.      SEND-PR: Lines starting with `SEND-PR' will be removed
  942.      SEND-PR: automatically as well as all comments (the text
  943.      SEND-PR: below enclosed in `<' and `>').
  944.      SEND-PR: Please consult the manual if you are not sure
  945.      SEND-PR: how to fill out a problem report.
  946.      SEND-PR:
  947.      SEND-PR: Choose from the following categories:
  948.      SEND-PR:
  949.      SEND-PR:           bfd       binutils  bison
  950.      SEND-PR: byacc     clib      config    cvs         diff
  951.      SEND-PR: doc       emacs     flex      g++         gas
  952.      SEND-PR: gcc       gdb       glob      gprof       grep
  953.      SEND-PR: info      ispell    kerberos  ld          libg++
  954.      SEND-PR: libiberty make      makeinfo  mas         newlib
  955.      SEND-PR: other     patch     rcs       readline    send-pr
  956.      SEND-PR: test      texindex  texinfo   texinfo.tex
  957.      SEND-PR: bifrabulator  <---*note: this one is fake*
  958.      SEND-PR:
  959.      To: cygnus-bugs@cygnus.com
  960.      Subject:
  961.      From: jeffrey@imaginary.com
  962.      Reply-To: jeffrey@imaginary.com
  963.      X-send-pr-version: send-pr 3.101
  964.      
  965.      >Submitter-Id:  imaginary
  966.      >Originator:    Jeffrey Osier
  967.      >Organization:
  968.      Imaginary Software, Ltd.
  969.      >Confidential:  <[ yes | no ] (one line)>
  970.      >Synopsis:      <synopsis of the problem (one line)>
  971.      >Severity:      <[ non-critical | serious | critical ] (one line)>
  972.      >Priority:      <[ low | medium | high ] (one line)>
  973.      >Category:      <name of the product (one line)>
  974.      >Class:         <[sw-bug|doc-bug|change-request|support](oneline)>
  975.      >Release:       <release number or tag (one line)>
  976.      >Environment:
  977.               <machine, os, target, libraries (multiple lines)>
  978.      System: SunOS imaginary.com 4.1.1 1 sun4
  979.      Architecture: sun4
  980.      
  981.      >Description:
  982.             <precise description of the problem (multiple lines)>
  983.      >How-To-Repeat:
  984.             <code/input/activities to reproduce (multiple lines)>
  985.      >Fix:
  986.      -----Emacs: *send-pr*   (send-pr Fill)----All------------------
  987.      >Category: other[]
  988.  
  989.    We know from past experience that we need to set certain information
  990. into each field, so we compile all the information we know about our
  991. problem.  We have some sample code which we know should work, even
  992. though it doesn't, so we'll include that.  Below is the completed PR;
  993. we send this using `C-c C-c'.  (The comments have been truncated).
  994.  
  995.      SEND-PR: Lines starting with `SEND-PR' will be removed
  996.      SEND-PR: automatically as well as all comments (the text
  997.      SEND-PR: ...
  998.      SEND-PR:
  999.      To: cygnus-bugs@cygnus.com
  1000.      Subject: bifrabulator routines don't match
  1001.      From: jeffrey@imaginary.com
  1002.      Reply-To: jeffrey@imaginary.com
  1003.      X-send-pr-version: send-pr 3.101
  1004.      
  1005.      >Submitter-Id:  imaginary
  1006.      >Originator:    Jeffrey Osier
  1007.      >Organization:
  1008.      Imaginary Software, Ltd.
  1009.      >Confidential:  no
  1010.      >Synopsis:      bifrabulator routines don't match
  1011.      >Severity:      serious
  1012.      >Priority:      medium
  1013.      >Category:      bifrabulator
  1014.      >Class:         sw-bug
  1015.      >Release:       progressive-930101
  1016.      >Environment:
  1017.      System: SunOS imaginary.com 4.1.1 1 sun4
  1018.      Architecture: sun4 (SPARC)
  1019.      
  1020.      >Description:
  1021.         the following code I fed into the bifrabulator came back
  1022.         with a strange error.  apparently, the prestidigitation
  1023.         routine doesn't match with the whatsitsname in all cases.
  1024.      
  1025.      >How-To-Repeat:
  1026.         call the bifrabulator on the following code.
  1027.         *code sample...*
  1028.      
  1029.      >Fix:
  1030.      -----Emacs: *send-pr*   (send-pr Fill)----All------------------
  1031.      To send the problem report use: C-c C-c
  1032.  
  1033.    We type `C-c C-c', and off it goes.  Now, we depend on Cygnus
  1034. Support to figure out the answer to our problem.
  1035.  
  1036.    Soon afterward, we get the following message from Cygnus:
  1037.  
  1038.      From: gnats (GNATS management)
  1039.      Sender: gnats-admin
  1040.      Reply-To: hacker@cygnus.com
  1041.      To: jeffrey@imaginary.com
  1042.      Subject: Re: bifrabulator/1425: routines don't match
  1043.      
  1044.      Thank you very much for your problem report.
  1045.      It has the internal identification: g++/1425.
  1046.      The individual assigned to look at your bug is:  hacker
  1047.      (F.B. Hacker)
  1048.      
  1049.      Category: bifrabulator
  1050.      Responsible: hacker
  1051.      Synopsis: bifrabulator routines don't match
  1052.      Arrival-Date: Sat Feb 30 03:12:55 1993
  1053.  
  1054. This is our receipt that the bug has been accepted and forwarded to the
  1055. responsible party.
  1056.  
  1057. A while later, we get the analysis:
  1058.  
  1059.      To:  jeffrey@imaginary.com
  1060.      From:  hacker@cygnus.com
  1061.      Subject:  Re: bifrabulator/1425: routines don't match
  1062.      Reply-To: hacker@cygnus.com
  1063.      
  1064.      Got your message, Jeff.  It seems that the bifrabulator was
  1065.      confusing the prestidigitation routines with the realitychecker
  1066.      when lexically parsing the whatsitsname.
  1067.      
  1068.      I'm working on robustisizing the bifrabulator now.
  1069.      
  1070.      How about lunch next week?
  1071.      --
  1072.      F.B. Hacker
  1073.      Cygnus Support, Mountain View, CA  415 903 1400
  1074.      #include <std-disclaimer.h>
  1075.  
  1076. About the same time, we get another message from Cygnus.
  1077.  
  1078.      From: hacker@cygnus.com
  1079.      To:  jeffrey@imaginary.com
  1080.      Subject:  Re: bifrabulator/1425: doesn't match prestidig
  1081.      Reply-To:  hacker@cygnus.com
  1082.      
  1083.      
  1084.                   `F.B. Hacker' changed the state to `analyzed'.
  1085.      
  1086.      State-Changed-From-To: open-analyzed
  1087.      State-Changed-By: hacker
  1088.      State-Changed-When: Fri Feb 31 1993 08:59:16 1993
  1089.      State-Changed-Why:
  1090.          figured out the problem, working on a patch this afternoon
  1091.      --
  1092.      F.B. Hacker
  1093.      Cygnus Support, Mountain View, CA  415 903 1400
  1094.      #include <std-disclaimer.h>
  1095.  
  1096. The bug has now been analyzed, and Cygnus is working on a solution.
  1097.  
  1098. Sometime later, we get more mail from F.B.:
  1099.  
  1100.      To:  jeffrey@imaginary.com
  1101.      From:  hacker@cygnus.com
  1102.      Subject:  Re: bifrabulator/1425: routines don't match
  1103.      Reply-To: hacker@cygnus.com
  1104.      
  1105.      There's a patch now that you can ftp over and check out.
  1106.      
  1107.      Hey, that joke you sent me was great!  The one about the
  1108.      strings walking into a bar...  my boss laughed for an hour!
  1109.      --
  1110.      F.B. Hacker
  1111.      Cygnus Support, Mountain View, CA  415 903 1400
  1112.      #include <std-disclaimer.h>
  1113.  
  1114.      From: hacker@cygnus.com
  1115.      To:  jeffrey@imaginary.com
  1116.      Subject:  Re: bifrabulator/1425: doesn't match prestidig
  1117.      Reply-To:  hacker@cygnus.com
  1118.      
  1119.      
  1120.                   `F.B. Hacker' changed the state to `feedback'.
  1121.      
  1122.      State-Changed-From-To: analyzed-feedback
  1123.      State-Changed-By: hacker
  1124.      State-Changed-When: Fri Feb 31 1993 23:43:16 1993
  1125.      State-Changed-Why:
  1126.          got the patch finished, notified Jeff at Imaginary Software
  1127.      --
  1128.      F.B. Hacker
  1129.      Cygnus Support, Mountain View, CA  415 903 1400
  1130.      #include <std-disclaimer.h>
  1131.  
  1132. The bug has gone into "feedback" status now, until we get the patch,
  1133. install it and test it.  When everything tests well, we can mail F.B.
  1134. back and tell him the bug's been fixed, and he can change the state of
  1135. the PR from "feedback" to "closed".
  1136.  
  1137.    Following is a list of valid `>Category:' entries that are supported
  1138. by Cygnus.
  1139.  
  1140. * Menu:
  1141.  
  1142. * Valid Categories::
  1143.  
  1144. 
  1145. File: send-pr.info,  Node: Valid Categories,  Up: An Example
  1146.  
  1147. Valid Categories
  1148. ================
  1149.  
  1150. `bfd'
  1151.      GNU binary file descriptor library.
  1152.  
  1153. `bifrabulator'
  1154.      This one doesn't actually exist.
  1155.  
  1156. `binutils'
  1157.      GNU utilities for binary files (`ar', `nm', `size'...).
  1158.  
  1159. `bison'
  1160.      GNU parser generator.
  1161.  
  1162. `byacc'
  1163.      Free parser generator.
  1164.  
  1165. `config'
  1166.      Cygnus Support Software configuration and installation.
  1167.  
  1168. `cvs'
  1169.      Concurrent Version System.
  1170.  
  1171. `diff'
  1172.      GNU `diff' program.
  1173.  
  1174. `doc'
  1175.      Documentation and manuals.
  1176.  
  1177. `emacs'
  1178.      GNU Emacs editor and related functions.
  1179.  
  1180. `flex'
  1181.      GNU lexical analyzer.
  1182.  
  1183. `g++'
  1184.      GNU C++ compiler.
  1185.  
  1186. `gas'
  1187.      GNU assembler.
  1188.  
  1189. `gcc'
  1190.      GNU C compiler.
  1191.  
  1192. `gdb'
  1193.      GNU source code debugger.
  1194.  
  1195. `glob'
  1196.      The filename globbing functions.
  1197.  
  1198. `gprof'
  1199.      GNU profiler.
  1200.  
  1201. `grep'
  1202.      GNU `grep' program.
  1203.  
  1204. `info'
  1205.      GNU `info' hypertext reader.
  1206.  
  1207. `ispell'
  1208.      GNU spelling checker.
  1209.  
  1210. `kerberos'
  1211.      Kerberos authentication system.
  1212.  
  1213. `ld'
  1214.      GNU linker.
  1215.  
  1216. `libc'
  1217.      Cygnus Support C Support Library.
  1218.  
  1219. `libg++'
  1220.      GNU C++ class library.
  1221.  
  1222. `libiberty'
  1223.      GNU `libiberty' library.
  1224.  
  1225. `libm'
  1226.      Cygnus Support C Math Library.
  1227.  
  1228. `make'
  1229.      GNU `make' program.
  1230.  
  1231. `makeinfo'
  1232.      GNU utility to build Info files from Texinfo documents.
  1233.  
  1234. `mas'
  1235.      GNU Motorola syntax assembler.
  1236.  
  1237. `newlib'
  1238.      Cygnus Support C Support and Math Libraries.
  1239.  
  1240. `patch'
  1241.      GNU bug patch program.
  1242.  
  1243. `gnats'
  1244.      GNU Problem Report Management System.
  1245.  
  1246. `rcs'
  1247.      Revision Control System.
  1248.  
  1249. `readline'
  1250.      GNU `readline' library.
  1251.  
  1252. `send-pr'
  1253.      GNU Problem Report submitting program.
  1254.  
  1255. `test'
  1256.      Category to use when testing `send-pr'.
  1257.  
  1258. `texindex'
  1259.      GNU documentation indexing utility.
  1260.  
  1261. `texinfo'
  1262.      GNU documentation macros.
  1263.  
  1264. `other'
  1265.      Anything which is not covered by the above categories.
  1266.  
  1267. 
  1268. File: send-pr.info,  Node: Installing send-pr,  Next: Index,  Prev: An Example,  Up: Top
  1269.  
  1270. Installing `send-pr' on your system
  1271. ***********************************
  1272.  
  1273.    If you receive `send-pr' as part of a larger software distribution,
  1274. it probably gets installed when the full distribution is installed.  If
  1275. you are using GNATS at your site as well, you must decide where
  1276. `send-pr' sends Problem Reports by default; see *Note Setting a default
  1277. SITE: default site.
  1278.  
  1279. * Menu:
  1280.  
  1281. * installation::   installing `send-pr' by itself
  1282. * default site::   setting a default site
  1283.  
  1284. 
  1285. File: send-pr.info,  Node: installation,  Next: default site,  Up: Installing send-pr
  1286.  
  1287. Installing `send-pr' by itself
  1288. ==============================
  1289.  
  1290.    Install `send-pr' by following these steps (you may need `root'
  1291. access in order to change the `aliases' file and to install `send-pr'):
  1292.  
  1293.    * Unpack the distribution into a directory which we refer to as
  1294.      SRCDIR.
  1295.  
  1296.    * Edit the file `Makefile' to reflect local conventions.
  1297.      Specifically, you should edit the variable `prefix' to alter the
  1298.      installation location.  The default is `/usr/local'.  All files are
  1299.      installed under `prefix' (see below).
  1300.  
  1301.    * *Run*
  1302.           make all install [ info ] [ install-info ] [ clean ]
  1303.  
  1304.      The targets mean the following:
  1305.  
  1306.     `all'
  1307.           Builds `send-pr' and `install-sid'
  1308.  
  1309.     `install'
  1310.           Installs the following:
  1311.  
  1312.          `install-sid'
  1313.          `send-pr'
  1314.                into `PREFIX/bin'
  1315.  
  1316.          `send-pr.1'
  1317.                into `PREFIX/man/man1'
  1318.  
  1319.          `SITE'
  1320.                the list of valid CATEGORIES for the Support Site from
  1321.                which you received `send-pr', installed as
  1322.                `PREFIX/lib/gnats/SITE'
  1323.  
  1324.          `send-pr.el'
  1325.                into `PREFIX/lib/emacs/lisp'(1)
  1326.  
  1327.     `info (*optional*)'
  1328.           Builds `send-pr.info' from `send-pr.texi'
  1329.           (`send-pr.info' is included with this distribution)
  1330.  
  1331.     `install-info (*optional*)'
  1332.           Installs `send-pr.info' into `PREFIX/info'
  1333.  
  1334.     `clean (*optional*)'
  1335.           Removes all intermediary build files that can be rebuilt from
  1336.           source code
  1337.  
  1338.    * Run
  1339.  
  1340.           install-sid YOUR-SID
  1341.  
  1342.      where YOUR-SID is the identification code you received with
  1343.      `send-pr'.  `send-pr' automatically inserts this value into the
  1344.      template field `>Submitter-Id:'.  If you've downloaded `send-pr'
  1345.      from the Net, use `net' for this value.
  1346.  
  1347.    * Place the following line in `PREFIX/lib/emacs/lisp/default.el', or
  1348.      instruct your users to place the following line in their `.emacs'
  1349.      files:
  1350.  
  1351.           (autoload 'send-pr "send-pr" "Submit a Problem Report." t)
  1352.  
  1353.    * Create a mail alias for the Support Site from which you received
  1354.      `send-pr', and for every site with which you wish to use `send-pr'
  1355.      to communicate.  Each alias must have a suffix of `-gnats'.  The
  1356.      Support Site(s) will provide the correct addresses where these
  1357.      aliases should point.  For instance, edit your mail aliases file
  1358.      to contain something like:
  1359.  
  1360.           # support sites; for use with send-pr
  1361.           cygnus-gnats:     bugs@cygnus.com            # Cygnus Support
  1362.           bumblebee-gnats:  bumblebugs@bumblebee.com   # Bumblebee Inc.
  1363.           mycompany-gnats:  bugs@my.company.com (*if you use GNATS locally*)
  1364.  
  1365.      `send-pr' automatically searches for these aliases when you type
  1366.  
  1367.           send-pr cygnus
  1368.           send-pr bumblebee
  1369.           send-pr SITE...
  1370.  
  1371.      `send-pr' also uses SITE to determine the categories of problems
  1372.      accepted by the site in question by looking in
  1373.  
  1374.           PREFIX/lib/gnats/SITE
  1375.  
  1376.    ---------- Footnotes ----------
  1377.  
  1378.    (1) If your main Emacs lisp repository is in a different directory
  1379. from this, substitute that directory for `PREFIX/lib/emacs/lisp'.
  1380.  
  1381. 
  1382. File: send-pr.info,  Node: default site,  Prev: installation,  Up: Installing send-pr
  1383.  
  1384. Setting a default SITE
  1385. ======================
  1386.  
  1387.    `send-pr' is capable of sending Problem Reports to any number of
  1388. Support Sites, using mail aliases which have `-gnats' appended them.
  1389. `send-pr' automatically appends the suffix, so that when you type
  1390.  
  1391.      send-pr SITE
  1392.  
  1393. the Problem Report goes to the address noted in the `aliases' file as
  1394. `SITE-gnats'.  You can do this in the Emacs version of `send-pr' by
  1395. invoking the program with
  1396.  
  1397.      C-u M-x send-pr
  1398.  
  1399. You are prompted for SITE.
  1400.  
  1401.    SITE is also used to error-check the `>Category:' field, as a
  1402. precaution against sending mistaken information (and against sending
  1403. information to the wrong site).
  1404.  
  1405.    You may also simply type
  1406.  
  1407.      send-pr
  1408.  
  1409. from the shell (or `M-x send-pr' in Emacs), and the Problem Report you
  1410. generate will be sent to the SITE, which is usually the site from which
  1411. you received your distribution of `send-pr'.  If you use GNATS at your
  1412. own organization, the default is usually your local address for
  1413. reporting problems.
  1414.  
  1415.    To change this, simply edit the file `Makefile' before installing
  1416. and change the line
  1417.  
  1418.      GNATS_SITE = SITE
  1419.  
  1420. to reflect the site where you wish to send PRs by default.
  1421.  
  1422. 
  1423. File: send-pr.info,  Node: Index,  Prev: Installing send-pr,  Up: Top
  1424.  
  1425. Index
  1426. *****
  1427.  
  1428. * Menu:
  1429.  
  1430. * *analyzed* state:                      States.
  1431. * *change-request* class:                Problem Report fields.
  1432. * *closed* state:                        States.
  1433. * *critical* severity problems:          Problem Report fields.
  1434. * *doc-bug* class:                       Problem Report fields.
  1435. * *duplicate* class:                     Problem Report fields.
  1436. * *Enumerated* data types:               Fields.
  1437. * *feedback* state:                      States.
  1438. * *high* priority problems:              Problem Report fields.
  1439. * *low* priority problems:               Problem Report fields.
  1440. * *medium* priority problems:            Problem Report fields.
  1441. * *MultiText* data types:                Fields.
  1442. * *non-critical* severity problems:      Problem Report fields.
  1443. * *open* state:                          States.
  1444. * *serious* severity problems:           Problem Report fields.
  1445. * *support* class:                       Problem Report fields.
  1446. * *suspended* state:                     States.
  1447. * *sw-bug* class:                        Problem Report fields.
  1448. * *Text* data types:                     Fields.
  1449. * >Arrival-Date::                        Problem Report fields.
  1450. * >Audit-Trail::                         Problem Report fields.
  1451. * >Category::                            Problem Report fields.
  1452. * >Class::                               Problem Report fields.
  1453. * >Confidential::                        Problem Report fields.
  1454. * >Description::                         Problem Report fields.
  1455. * >Environment::                         Problem Report fields.
  1456. * >Fix::                                 Problem Report fields.
  1457. * >How-To-Repeat::                       Problem Report fields.
  1458. * >Number::                              Problem Report fields.
  1459. * >Organization::                        Problem Report fields.
  1460. * >Originator::                          Problem Report fields.
  1461. * >Priority::                            Problem Report fields.
  1462. * >Release::                             Problem Report fields.
  1463. * >Responsible::                         Problem Report fields.
  1464. * >Severity::                            Problem Report fields.
  1465. * >State::                               Problem Report fields.
  1466. * >Submitter-Id: <1>:                    using send-pr.
  1467. * >Submitter-Id::                        Problem Report fields.
  1468. * >Synopsis::                            Problem Report fields.
  1469. * >Unformatted::                         Problem Report fields.
  1470. * an example:                            An Example.
  1471. * appending PRs <1>:                     using send-pr.
  1472. * appending PRs:                         Problem Report fields.
  1473. * Arrival-Date field:                    Problem Report fields.
  1474. * Audit-Trail field:                     Problem Report fields.
  1475. * automatic notification:                States.
  1476. * bad Problem Reports:                   using send-pr.
  1477. * bifrabulator:                          An Example.
  1478. * blank PR template:                     An Example.
  1479. * Category field:                        Problem Report fields.
  1480. * Class field:                           Problem Report fields.
  1481. * command line options:                  send-pr from the shell.
  1482. * comment section in the PR template:    using send-pr.
  1483. * completed Problem Report:              An Example.
  1484. * completion in Emacs:                   send-pr in Emacs.
  1485. * Confidential field:                    Problem Report fields.
  1486. * confidentiality in PRs:                Problem Report fields.
  1487. * Cygnus Support:                        An Example.
  1488. * database similarities:                 Fields.
  1489. * default PR template:                   An Example.
  1490. * default SITE:                          default site.
  1491. * Description field:                     Problem Report fields.
  1492. * details about send-pr:                 send-pr in detail.
  1493. * editing and sending PRs:               Invoking send-pr.
  1494. * effective problem reporting:           Helpful hints.
  1495. * Emacs:                                 send-pr in Emacs.
  1496. * Environment field:                     Problem Report fields.
  1497. * errors:                                using send-pr.
  1498. * example of a completed PR:             An Example.
  1499. * example of a default template:         An Example.
  1500. * example of a list of valid categories: Valid Categories.
  1501. * example of a state change:             An Example.
  1502. * example PR:                            An Example.
  1503. * example Problem Report:                Fields.
  1504. * field format:                          Problem Report fields.
  1505. * fields:                                Fields.
  1506. * fields - list:                         Problem Report fields.
  1507. * final state ("closed"):                States.
  1508. * Fix field:                             Problem Report fields.
  1509. * foreword to send-pr:                   Top.
  1510. * format:                                Fields.
  1511. * From: header:                          Mail header fields.
  1512. * generating new PRs:                    Invoking send-pr.
  1513. * GNATS:                                 Top.
  1514. * GNATS database fields:                 Problem Report fields.
  1515. * GNATS fields - list:                   Problem Report fields.
  1516. * GNU software support:                  An Example.
  1517. * helpful hints:                         Helpful hints.
  1518. * How-To-Repeat field:                   Problem Report fields.
  1519. * Imaginary Software, Ltd.:              An Example.
  1520. * information to submit:                 Helpful hints.
  1521. * initial state ("open"):                States.
  1522. * installation:                          Installing send-pr.
  1523. * installation procedure:                installation.
  1524. * interactive interface:                 send-pr in Emacs.
  1525. * Internet standard RFC-822:             Mail header fields.
  1526. * introduction to send-pr:               Top.
  1527. * invalid Problem Reports:               using send-pr.
  1528. * invoking send-pr:                      Invoking send-pr.
  1529. * invoking send-pr from Emacs:           send-pr in Emacs.
  1530. * invoking send-pr from the shell:       send-pr from the shell.
  1531. * kinds of helpful information:          Helpful hints.
  1532. * life-cycle of a Problem Report:        States.
  1533. * listing valid categories:              send-pr from the shell.
  1534. * mail header fields:                    Mail header fields.
  1535. * mail header section:                   using send-pr.
  1536. * name completion in Emacs:              send-pr in Emacs.
  1537. * Number field:                          Problem Report fields.
  1538. * Organization field:                    Problem Report fields.
  1539. * Originator field:                      Problem Report fields.
  1540. * other mail <1>:                        using send-pr.
  1541. * other mail:                            Problem Report fields.
  1542. * overview to send-pr:                   Top.
  1543. * PR confidentiality:                    Problem Report fields.
  1544. * Priority field:                        Problem Report fields.
  1545. * Problem Report data types:             Fields.
  1546. * Problem Report format:                 Fields.
  1547. * Problem Report states:                 States.
  1548. * Problem Report template:               Fields.
  1549. * Problem Reports:                       send-pr in detail.
  1550. * related mail <1>:                      using send-pr.
  1551. * related mail:                          Problem Report fields.
  1552. * Release field:                         Problem Report fields.
  1553. * Reply-To: header:                      Mail header fields.
  1554. * Report all the facts!:                 Helpful hints.
  1555. * Responsible field:                     Problem Report fields.
  1556. * Responsible-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields.
  1557. * Responsible-Changed-By: in >Audit-Trail:: Problem Report fields.
  1558. * Responsible-Changed-When: in >Audit-Trail:: Problem Report fields.
  1559. * Responsible-Changed-Why: in >Audit-Trail:: Problem Report fields.
  1560. * sample Problem Report:                 Fields.
  1561. * saving related mail <1>:               using send-pr.
  1562. * saving related mail:                   Problem Report fields.
  1563. * send-pr fields <1>:                    send-pr from the shell.
  1564. * send-pr fields:                        using send-pr.
  1565. * send-pr within Emacs:                  send-pr in Emacs.
  1566. * sending PRs:                           Invoking send-pr.
  1567. * setting a default SITE:                default site.
  1568. * Severity field:                        Problem Report fields.
  1569. * shell invocation:                      send-pr from the shell.
  1570. * state change example:                  An Example.
  1571. * State field:                           Problem Report fields.
  1572. * state--"analyzed":                     States.
  1573. * state--"closed":                       States.
  1574. * state--"feedback":                     States.
  1575. * state--"open":                         States.
  1576. * state--"suspended":                    States.
  1577. * State-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields.
  1578. * State-Changed-By: in >Audit-Trail::    Problem Report fields.
  1579. * State-Changed-When: in >Audit-Trail::  Problem Report fields.
  1580. * State-Changed-Why: in >Audit-Trail::   Problem Report fields.
  1581. * states of Problem Reports:             States.
  1582. * Subject: header:                       Mail header fields.
  1583. * Submitter-Id field <1>:                using send-pr.
  1584. * Submitter-Id field:                    Problem Report fields.
  1585. * subsequent mail <1>:                   using send-pr.
  1586. * subsequent mail:                       Problem Report fields.
  1587. * Synopsis field:                        Problem Report fields.
  1588. * template:                              using send-pr.
  1589. * template comment section:              using send-pr.
  1590. * To: header:                            Mail header fields.
  1591. * Unformatted field:                     Problem Report fields.
  1592. * Using and Porting GNU CC:              Helpful hints.
  1593. * using send-pr:                         Invoking send-pr.
  1594. * using send-pr from within Emacs:       send-pr in Emacs.
  1595. * valid categories:                      Valid Categories.
  1596.  
  1597.  
  1598. 
  1599. Tag Table:
  1600. Node: Top856
  1601. Node: send-pr in detail2868
  1602. Node: States3707
  1603. Node: Fields5139
  1604. Node: Mail header fields8808
  1605. Node: Problem Report fields9673
  1606. Node: Invoking send-pr17063
  1607. Node: using send-pr17520
  1608. Node: send-pr in Emacs24707
  1609. Node: send-pr from the shell29117
  1610. Node: Helpful hints31690
  1611. Node: An Example34799
  1612. Node: Valid Categories43903
  1613. Node: Installing send-pr45722
  1614. Node: installation46289
  1615. Node: default site49513
  1616. Node: Index50770
  1617. 
  1618. End Tag Table
  1619.